跳转至

Slate FAQ（Slate 常见问题解答(FAQ)）

The following are a few frequently asked questions about Slate. For general information, see Slate documentation.

--

Introduction to debugging slate

In many ways, Slate is the most complex Foundry tool available to developers. Slate puts the tools to build a single-page web application into an approachable package, but provides few built-in rails, instead allowing a wide degree of freedom in implementing different patterns. This flexibility is a powerful feature and allows a diverse array of applications, dashboards, and workflow tools to be built in Slate, but it also means it is quite easy to implement anti-patterns that result in slow performance or confusion, non-deterministic application behavior.

Getting to the root cause of the most complex of these types of implementation issues requires reverse engineering the application logic in the context of Slate development best practices as well as general principles of web application development.

We will break these down below to call out places where we have seen anti-patterns emerge and suggest improved practices or guide solutions. We will start with relevant questions of web technology:

1. Front-end web technology

  • How a web browser works.
  • How network requests are made from a browser and responded to from other services.
  • How browser resources are allocated to the rendering and JavaScript execution of a particular website.
  • How HTML and CSS work together to define how a website looks.
  • How JavaScript is compiled and executed.

While this knowledge is not specific to Slate, misunderstanding these fundamentals is at the root of many questions about performance, layout, and styling for Slate apps which are effectively custom-built web applications.

W3Schools ↗ amongst many other sources provide basic tutorials in these topics.

2. Postgres and SQL

It is also helpful to be familiar with SQL and how a Postgres database constructs and executes a query, since most applications retrieve their data with queries against the Postgres instance where data is synced from Foundry datasets for application access.

Many questions around query development, errors, performance are not Slate-specific and can be answered with common search queries, often in the form: Postgres + [question].

Slate, however, is not particularly friendly in parsing and providing error messages generated by Postgres, and we recommend you review the section below for common causes and remedies for these issues and refer to the Postgres Performance and Tuning guidelines for more detailed information.

3. Slate-specific knowledge

Building complex applications in Slate can take some getting used to and many anti-patterns can arise from "imposing" other application development concepts onto Slate, rather than working within framework provided by Slate. There are often implicit "correct" patterns for implementing a given functionality that best mesh with these fundamental Slate concepts.

Much of this complexity is covered in Understand dependencies, which includes discussions of the core components of Slate (the Dependency graph, the Event framework, widgets, queries, functions, and so on), common patterns (and common anti-patterns), and best practices for design and implementation.

We recommend developers and support engineers to have familiarity with this documentation as many common questions can be answered with content already explained in depth. In many cases, the best way to answer a question is not to try and solve the specific instance - for example, by opening the app and trying to reverse-engineer the user's development decisions - but rather to understand the general category of failure the user is encountering and direct them to the relevant discussion in any of the following:

For some of the most common cases, this FAQ documentation is a short-cut to brief explanations and useful reference material.

Return to top

Queries

Failed queries

Query-related questions come in many flavors and figuring out the root cause can point to many resolution strategies. In some cases, the issue presents with an explicit error message, but in others, there may be no error message or the conditions of failure may be non-deterministic (in that sometimes they happen, and sometimes they do not). The troubleshooting steps below present some common root causes and related resolution strategies.

To troubleshoot, perform the following steps:

Sometimes a query goes against general usage patterns for synchronous network requests:

  • Queries that try to return too much data to the browser.
  • Queries should return less than 10,000 rows as rough rule of thumb.
    • Sometimes the query will explicitly return with an error that says 'too many rows', but often, the query will succeed though the rest of the application will be very slow. In these cases, look for queries that are returning lots of rows and try to reduce the returned amount.
  • If you are trying to display a table with lots of rows or otherwise need to present raw rows to the user, use the LIMIT and OFFSET statements to implement a paging workflow, either with the built-in properties of the Table widget or with a custom workflow.
  • Queries that are so large that they take a long time to simply make the request.
  • Queries should take < 5s round-trip.
  • If you have a query with a large payload, consider pushing more of the logic embedded in the query into the transformation layer producing the datasets.

For this general category of question, refer to Optimize indexes and schema design documentation and consider that applications should be structured, so the data returned to the browser is in its final form, rather than in need of heavy manipulation in JavaScript functions.

Sometimes the issue is instead related to how Postgres interprets and responds to the request:

  • Queries that are slow because they are not optimally structured.
  • Queries that are slow because the dataset is not or is incorrectly indexed.
  • Queries that have incorrect syntax.

These types of questions are often answered with a search of Postgres + [error message] of Postgres + [desired query]. For all questions related to troubleshooting or investigating query performance, refer to the Postgres query performance and tuning guide.

And sometimes the issue is rather with how and when Slate executes queries according to the developer's configuration:

  • Queries fail non-deterministically on page load.
  • Refer to the Managing query execution section of the Best Practices guide.
  • Queries that return an unhelpful error at 20s (the Slate timeout period)
  • The requests made through Slate queries timeout on the Slate side at 20s, regardless of what happening on the server-side of the request. The definitive diagnosis for this failure mode is to view the application in View mode with the Google Chrome Network Inspector open when you refresh the page. This will show the duration of each query request and if you see a query turn red at 20s, you can be sure the failure is because Slate has timed out the query.
  • Resolve this both by improving query performance: Postgres query performance and tuning and Controlling query execution.
  • For more on timeouts specifically, review the next section on Postgres query times out.
  • Queries that fail in certain circumstances (because the Handlebars rendering is not well protected).
  • If you have Handlebars statements in your query, make sure they're protected by {{#if}} statements or through logic in a function against null values or other edge cases.
  • Queries that execute at the wrong time or fail to execute.
  • Make sure you understand why things happen in Slate and that you are appropriately controlling query execution. For complex applications or those that rely overly-heavily on events, the note on Event Madness is relevant.

Return to top

Postgres query times out

When queries time out, there are two primary factors at play:

  • Data scale - how many rows are in the table in Postgres and how many rows you are returning from the query.
  • Query optimization - how "expensive" is the query.

As an application developer, it is necessary to understand these factors and how they affect your query. Neither are Slate nor Foundry-specific, so you can make progress through searching for Postgres SQL query performance and find the general best practices as well as tips in the Postgres Query Performance and Tuning guide.

To troubleshoot, perform the following steps:

A few pointers that may help, based on frequently seen issues from app developers:

  • Data Scale: Limit the scale of the dataset you are syncing to Postgres. For example, if you only need one year of data, do not sync a dataset of all time and then filter in your query.

  • Data Scale: Reduce the number of columns in the table. For example, if you only select a few columns in the query, drop them in a transform before syncing the table to avoid overhead.

  • Data Scale: Return as few rows as possible. If you are displaying the raw rows, use OFFSET and PAGING to retrieve further rows rather than returning more than a few hundred rows in response to any query.

  • Query Optimization: Avoid expensive SQL commands where possible. Frequent offenders are COALESCE, DISTINCT, any JOIN on columns that are not "complete" (such as some values are null) or WHERE clause filters that involve leading wildcards (%) or complex match expressions.

  • Query Optimization: Push work upstream. This includes data cleanup (removing nulls, formatting dates, mapping display values) and metrics calculations (monthly totals, averages across buckets, etc.) should be pushed into the transforms layer when possible. If you need to allow users to customize these through filters, you can still "pre-aggregate" metrics across a few dimensions, then do a much simpler query to sum/average/etc. across just a few rows that meet those criteria.

  • Query Optimization: Use EXPLAIN ANALYZE do get the query plan and understand how Postgres is interpreting your query. This will help identify bottlenecks where the time is being spent and you can further target your optimizations. Here ↗ is a useful primer on reading and understanding the results.

  • Query Optimization: Review Optimize queries in Postgres.

Return to top

Cannot reference columns in my Postgres query

In Postgres, column names are assumed to be lower case. Since Foundry allows flexible casing and spacing in column names, when a table is indexed to Postres, the table is wrapped in " (double quote) characters to preserve the casing.

This means if the column has capitalized characters, you will need to wrap the reference in your SQL query in double quotes as well.

You can read more about this behavior on StackOverflow ↗.

To troubleshoot, perform the following steps:

Queries with mishandled column identifiers will often have an error such as:

ERROR: column mixedcasecolumn does not exist HINT: Perhaps you meant to reference the column "Mixed Case Column"

In these cases, best practice is to update the dataset in question to use column identifiers that meet Postgres defaults, which is generally lowercase characters with underscores replacing spaces. Otherwise, simply ensure that the identifiers are properly encapsulated in double quotes.

Phonograph queries and general Foundry writeback

More advanced users building complex applications with data write-back to Foundry datasets will be using the Phonograph service. Ensure that the Phonograph Reference Application is available on your Foundry instance.

Most common questions are answered there with example queries and widget patterns. In addition, most of the content from the reference example can be reviewed at How To: Writeback to Foundry.

To troubleshoot, perform the following steps:

Read the documentation carefully as most common issues are covered, though this is a deep and complex feature. Please reach out to the Palantir support team with particular questions or issues.

Return to top

Phonograph query truncates text on submit

In an edge case configuration, you can observe writeback queries that reference one or more Text Area widgets send a Phonograph request with only partial text. For instance, if the user enters long text like This is a test message for writeback and quickly presses the Submit button to trigger the writeback query, only This is a te might be included.

The underlying cause is the 0.5s debounce delay used by the Text Area widget to prevent the Dependency Graph from re-evaluating with every key press in the widget input. This delay means that the query will submit without the entire text if, and only if:

  • A text area widget is the last input filled in by a user, and,
  • The submit button is pressed less than 0.5s after the last character is entered into the text area.

To troubleshoot, perform the following steps:

The simplest solution is to tweak the user experience such that it is not possible to use the submit option within 0.5s of entering long text. For instance, adding in a confirmation dialog before submitting the query or simply re-ordering the form elements, so there is another field to complete after the text area widget.

Other solutions would be to swap the text area widget for a Text Input widget, which does not include the debounce delay. It is also possible to use a Toast widget as a delay buffer between the submit button press and the query execution to ensure that enough time passes that the full text is included.

Return to top

Functions

My function does not work

Functions in Slate are basic JavaScript executed in a sandbox from the rest of the application. They are purely user-generated code, so the majority of issues related to functions will at root be issues of misunderstanding or otherwise failing to correctly implement the desired functionality in JavaScript.

To troubleshoot, perform the following steps:

The basic steps of debugging are to simplify the function until it behaves in an expected way, then add back complexity in small steps until the unexpected behavior returns. At this point you have identified the point where further research is required to understand the correct way to implement the desired behavior.

An additional tool for debugging is the Chrome DevTools Debugger ↗. Consider also a related section on Debug using DevTool Add “breakpoints” to your function with a debugger; statement.

Then, with the Chrome DevTools panel open, click the Test button in the Function window. The function execution will pause at the breakpoint, and you can continue to step through the function code and view the values of variables.

Return to top

My function is not running when expected

Functions interact in unintuitive ways with the Events framework because in normal usage they are not called but instead are executed by the Dependency Graph when they are out-of-date with their inputs and their output is rendered to JSON for consumption by downstream dependencies.

To troubleshoot, perform the following steps:

If a function is behaving in an unexpected manner, confirm that you understand how they fit in to the Dependency Graph and Event Framework by reviewing the existing best practices documentation.

It's very rare to need a pattern where an Event calls the [f_myFunction].run action. An application attempting to rely on this pattern should be refactored to use the normal resolution of the dependency graph. Instead of triggering the function directly, instead update an upstream dependency, for example by triggering a query or setting the value of a referenced variable.

Return to top

Map widget

My GEOJSON is not rendering

The map widget supports rendering properly defined geojson map features, such as points and geometries. These can be dynamically generated or retrieved from a database, however the formatting is specific and can be difficult to achieve if it is created by hand or through a novel algorithm.

To troubleshoot, perform the following steps:

Review the GeoJSON in the Map Widget reference example. Try searching for it on your Foundry instance and if it is not available, file an issue.

Return to top

Styling

My style is not applied, or how do I override style [x]?

All styling in Slate ultimately translates into CSS. You can inspect any element of your application with the Chrome Inspector tool (Right-click > Inspect on any element) to see what classes are applied to that element and understand the document hierarchy.

To troubleshoot, perform the following steps:

Review the documentation section on Style to understand more deeply how and where styles are defined, applied, and rendered in Slate.

Return to top

Layout

Application rendering issues

In some configurations, if you attempt to configure a widget to be a “dynamic” width and height, instead you will find your widget rendered in a small box when the page loads. Triggering the [w_myWidget.resize] action causes the widget to render to the expected size.

This behavior is caused by a collision between CSS specifying the width and height of various widget elements as percentages - normally 100% - and the Flex property on one or more parent containers. With these collisions, Slate is unable to determine the correct dimensions of the element enclosing the widget at render-time and therefore renders the widget too small.

To troubleshoot, perform the following steps:

The appropriate pattern for implementing responsive widget dimensions is to only use the Flex configuration settings on the parent container(s) and child widgets. Do not set other width or height properties manually through CSS. To resolve, start with root child widget(s) and move up through all the parent widgets, removing any positional or dimensional CSS rules.

You can use margin and padding properties to inset or otherwise align child widgets. If you are comfortable with Flexbox CSS rules, you can use the Chrome Inspector to identify which elements and classes to target and provide overrides or additional Flexbox rules to achieve the exact desired behavior.

Return to top

My Slate app will not print / How do I export my App

Slate is optimized for rapid application development. The underlying framework imposes few limitations on the configurability of layout our styling. As a result, Slate is unable to generically render all applications in a manner suitable for print media or export. Application developers will need to invest time on an app-by-app basis to support printing.

To troubleshoot, perform the following steps:

The first and best option is to consider why there is a requirement or request to print your app. Do your users simply need a way to preserve the view they've created and reference it later or use it during a presentation?

In this case, consider using the built-in shareable view feature, which generates a unique URL that preserves the state of all widget selections and variables. Users can access this from the Actions dropdown menu in View mode.

If you really must print or export, then you will need to define additional media CSS styles to help your application render appropriately.

To start, you'll need to add at least this to the Global Styles:

@media print {
  @page {
    size: A4;
  }

  html, body , .ws-root-container.ws-sandbox {
    height: 600mm !important;
  }

  sl-app-view-actions {
    display: none !important;
  }
}

Printing responsive applications or any application with complex styling or layouts will be very difficult. In these cases, consider creating a “Print View” as a separate application that receives necessary inputs through URL parameters and generates a simplified view optimized for printing. This will increase the development cost and maintenance burden but will result in satisfactory behavior.

Return to top

Performance

My application is slow to load or sluggish in edit mode

Like all web applications, Slate uses browser resources in the end user's computer to execute JavaScript code and render the document model (DOM) defined in HTML with the styles specified in CSS. Some portion of these resources are constant; they are the overhead of working within the Slate framework. However, in cases of poor performance, the root cause is most often a form of application overload where the configuration defined in the course of developing the application demands too many resources from the browser to either render the application, execute the JavaScript, or simply store in memory the results of many large queries.

In some cases, a single function or query might be the cause. In this case, you can use the performance metrics in the Dependencies tab of an application to look at the Time in Node for various queries and functions. This metric represents the duration spent resolving that particular node on page load, which can help identify likely candidates for application bottlenecks.

In general, a best practice is to favor lightweight, well-bounded, single-serving applications and create large workflows or applications out of “clusters” of small application with deep linking between them.

Return to top

Configuration

The document is too large to save

Slate saves the application configuration as a JSON document, which generally has a size limit of 2,000,000 bytes of UTF-8 encoded characters. Attempts to save a Slate application with a configuration above the size limit will fail, and changes will need to be made to the application configuration to decrease the size. The JSON document of an opened Slate application can be retrieved through export.

Every part of a Slate application takes up configuration size to some degree, and editors should be conscious about both the scale of Slate applications being built, and the resources being embedded in the application configuration. The following are prevalent reasons for the overuse of configuration size, along with proposed solutions:

Base64 encoded images

Upload the image to Foundry and reference the image using the Image widget.

Large functions

Consider refactoring functions to extract common logic into function libraries.

Additionally, large functions may be better suited as Foundry Functions consumed via the Platform editor.

Large function libraries

While function libraries are shared across all pages of a Slate application to conserve space, javascript libraries can be quite large. Either refactor custom libraries to use shared logic, or use minified versions of external libraries.

Return to top

中文翻译

Slate 常见问题解答(FAQ)

以下是关于 Slate 的一些常见问题解答。 如需了解一般信息，请参阅 Slate 文档。

--

Slate 调试简介

从很多方面来看，Slate 是开发者可用的最复杂的 Foundry 工具。Slate 将构建单页 Web 应用的工具整合到一个易于使用的软件包中，但提供的内置约束很少，反而允许在实现不同模式时拥有广泛的自由度。这种灵活性是一个强大的功能，允许在 Slate 中构建多样化的应用、仪表盘和工作流工具，但这也意味着很容易实现导致性能缓慢、混乱或应用行为不确定的反模式(anti-patterns)。

要解决这些最复杂的实现问题的根本原因，需要在 Slate 开发最佳实践以及 Web 应用开发通用原则的背景下，对应用逻辑进行逆向工程。

我们将在下面进行分解，指出我们看到反模式出现的地方，并建议改进实践或指导解决方案。我们将从相关的 Web 技术问题开始：

1. 前端 Web 技术

  • Web 浏览器的工作原理。
  • 网络请求如何从浏览器发出并由其他服务响应。
  • 浏览器资源如何分配给特定网站的渲染和 JavaScript 执行。
  • HTML 和 CSS 如何协同工作来定义网站的外观。
  • JavaScript 如何被编译和执行。

虽然这些知识并非 Slate 特有，但误解这些基础知识是许多关于 Slate 应用（本质上是定制构建的 Web 应用）的性能、布局和样式问题的根源。

W3Schools ↗ 以及许多其他资源提供了这些主题的基础教程。

2. Postgres 和 SQL

熟悉 SQL 以及 Postgres 数据库如何构建和执行查询也很有帮助，因为大多数应用通过查询 Postgres 实例来检索数据，数据从 Foundry 数据集同步到该实例以供应用访问。

许多关于查询开发、错误、性能的问题并非 Slate 特有，可以通过常见的搜索查询来解答，通常形式为：Postgres + [问题]。

然而，Slate 在解析和提供 Postgres 生成的错误消息方面并不特别友好，我们建议您查看下面的章节，了解这些问题的常见原因和补救措施，并参考 Postgres 性能与调优 指南以获取更详细的信息。

3. Slate 特定知识

在 Slate 中构建复杂应用可能需要一些时间来适应，许多反模式源于将其他应用开发概念"强加"到 Slate 上，而不是在 Slate 提供的框架内工作。通常存在隐式的"正确"模式来实现与这些基本 Slate 概念最契合的特定功能。

这些复杂性的很大一部分在理解依赖关系中有所涵盖，其中包括对 Slate 核心组件（依赖图、事件框架、组件、查询、函数等）、常见模式（和常见反模式）以及设计和实现最佳实践的讨论。

我们建议开发者和支持工程师熟悉本文档，因为许多常见问题可以通过已经深入解释的内容来回答。在许多情况下，回答问题的最佳方式不是尝试解决特定实例——例如，打开应用并尝试逆向工程用户的开发决策——而是理解用户遇到的失败的一般类别，并将他们引导至以下任一文档中的相关讨论：

对于一些最常见的情况，本 FAQ 文档提供了简要解释和有用的参考资料的快捷方式。

返回顶部

查询(Queries)

查询失败

与查询相关的问题有多种形式，找出根本原因可以指向多种解决策略。在某些情况下，问题会显示明确的错误消息，但在其他情况下，可能没有错误消息，或者失败条件可能是不确定的（有时发生，有时不发生）。下面的故障排除步骤介绍了一些常见的根本原因和相关的解决策略。

要进行故障排除，请执行以下步骤：

有时查询违反了同步网络请求的一般使用模式：

  • 尝试向浏览器返回过多数据的查询。
  • 粗略的经验法则是，查询应返回少于 10,000 行。
    • 有时查询会明确返回一个错误，提示"行数过多"，但通常查询会成功，但应用的其余部分会非常慢。在这些情况下，查找返回大量行的查询并尝试减少返回的数量。
  • 如果您尝试显示包含大量行的表格，或者需要向用户呈现原始行，请使用 LIMIT 和 OFFSET 语句实现分页工作流，可以使用表格组件的内置属性，也可以使用自定义工作流。
  • 查询过大，以至于仅发出请求就需要很长时间。
  • 查询的往返时间应 < 5 秒。
  • 如果您的查询负载很大，请考虑将嵌入在查询中的更多逻辑推送到生成数据集(transformation layer)的转换层。

对于此类一般性问题，请参考优化索引和模式设计文档，并考虑应用的结构应使返回给浏览器的数据处于最终形式，而不是需要在 JavaScript 函数中进行大量操作。

有时问题与 Postgres 如何解释和响应请求有关：

  • 查询速度慢是因为结构不是最优的。
  • 查询速度慢是因为数据集未建立索引或索引不正确。
  • 查询语法不正确。

这类问题通常可以通过搜索 Postgres + [错误消息] 或 Postgres + [期望的查询] 来回答。对于所有与故障排除或调查查询性能相关的问题，请参考 Postgres 查询性能与调优 指南。

有时问题在于 Slate 根据开发者的配置如何以及何时执行查询：

  • 查询在页面加载时不确定地失败。
  • 请参考最佳实践指南中的管理查询执行部分。
  • 查询在 20 秒（Slate 超时期限）时返回无用的错误。
  • 通过 Slate 查询发出的请求在 Slate 端 在 20 秒时超时，无论请求的服务端发生了什么。此失败模式的明确诊断是，在刷新页面时，在查看模式下打开 Google Chrome 网络检查器(Network Inspector)查看应用。这将显示每个查询请求的持续时间，如果您看到查询在 20s 时变红，则可以确定失败是因为 Slate 已使查询超时。
  • 通过改进查询性能来解决此问题：Postgres 查询性能与调优 和控制查询执行。
  • 有关超时的更多具体信息，请查看下一节 Postgres 查询超时。
  • 查询在某些情况下失败（因为 Handlebars 渲染未得到良好保护）。
  • 如果您的查询中有 Handlebars 语句，请确保它们通过 {{#if}} 语句或通过函数中的逻辑针对 null 值或其他边缘情况进行保护。
  • 查询在错误的时间执行或执行失败。
  • 确保您理解 Slate 中事情发生的原因，并且您正在适当地控制查询执行。对于复杂应用或过度依赖事件的应用，关于"事件混乱(Event Madness)"的说明是相关的。

返回顶部

Postgres 查询超时

当查询超时时，有两个主要因素在起作用：

  • 数据规模(Data scale) - Postgres 表中有多少行，以及您从查询中返回多少行。
  • 查询优化(Query optimization) - 查询的"开销"有多大。

作为应用开发者，有必要理解这些因素以及它们如何影响您的查询。这些都不是 Slate 或 Foundry 特有的，因此您可以通过搜索 Postgres SQL query performance 来取得进展，并在 Postgres 查询性能与调优 指南中找到通用最佳实践以及技巧。

要进行故障排除，请执行以下步骤：

根据应用开发者经常遇到的问题，这里有一些可能有帮助的要点：

  • 数据规模：限制您同步到 Postgres 的数据集规模。例如，如果您只需要一年的数据，不要同步所有时间的数据集，然后在查询中过滤。

  • 数据规模：减少表中的列数。例如，如果您在查询中只选择几列，请在同步表之前在转换(transform)中删除它们以避免开销。

  • 数据规模：尽可能少地返回行。如果您正在显示原始行，请使用 OFFSET 和 PAGING 来检索更多行，而不是在任何查询的响应中返回超过几百行。

  • 查询优化：尽可能避免昂贵的 SQL 命令。常见的"罪魁祸首"包括 COALESCE、DISTINCT、任何在不"完整"的列（例如某些值为 null）上的 JOIN，或涉及前导通配符（%）或复杂匹配表达式的 WHERE 子句过滤器。

  • 查询优化：将工作推向上游。这包括数据清理（移除空值、格式化日期、映射显示值）和指标计算（月度总计、跨桶平均值等），应尽可能推入转换层。如果您需要允许用户通过过滤器自定义这些，您仍然可以跨几个维度"预聚合"指标，然后执行一个更简单的查询来对满足这些条件的仅几行进行求和/平均等操作。

  • 查询优化：使用 EXPLAIN ANALYZE 获取查询计划并理解 Postgres 如何解释您的查询。这将有助于识别时间花费在哪里的瓶颈，您可以进一步定位您的优化。这里 ↗ 是一个关于阅读和理解结果的有用入门指南。

  • 查询优化：查看在 Postgres 中优化查询。

返回顶部

无法在 Postgres 查询中引用列

在 Postgres 中，列名假定为小写。由于 Foundry 允许列名使用灵活的大小写和空格，当表被索引到 Postgres 时，表会被包裹在 "（双引号）字符中以保留大小写。

这意味着如果列包含大写字符，您也需要在 SQL 查询中将引用包裹在双引号中。

您可以在 StackOverflow ↗ 上阅读有关此行为的更多信息。

要进行故障排除，请执行以下步骤：

处理不当的列标识符的查询通常会显示如下错误：

ERROR: column mixedcasecolumn does not exist HINT: Perhaps you meant to reference the column "Mixed Case Column"

在这些情况下，最佳实践是更新相关数据集，以使用满足 Postgres 默认值的列标识符，这通常是使用下划线替换空格的小写字符。否则，只需确保标识符被正确地封装在双引号中。

Phonograph 查询和通用 Foundry 回写

构建具有数据写回 Foundry 数据集的复杂应用的高级用户将使用 Phonograph 服务。确保您的 Foundry 实例上提供了 Phonograph 参考应用(Phonograph Reference Application)。

大多数常见问题都可以在那里通过示例查询和组件模式得到解答。此外，参考示例中的大部分内容可以在如何：写回 Foundry 中查看。

要进行故障排除，请执行以下步骤：

仔细阅读文档，因为大多数常见问题都已涵盖，尽管这是一个深入且复杂的功能。如有特定问题或疑问，请联系 Palantir 支持团队。

返回顶部

Phonograph 查询在提交时截断文本

在一种边缘情况配置中，您可能会观察到引用一个或多个文本区域(Text Area)组件的写回查询仅发送部分文本的 Phonograph 请求。例如，如果用户输入长文本如 This is a test message for writeback 并快速按下提交(Submit)按钮以触发写回查询，可能只包含了 This is a te。

根本原因是文本区域组件使用的 0.5 秒防抖延迟(debounce delay)，以防止依赖图在组件输入中每次按键时都重新评估。这个延迟意味着查询将在以下情况下提交而不包含完整文本，当且仅当：

  • 文本区域组件是用户填写的最后一个输入，并且，
  • 在文本区域中输入最后一个字符后不到 0.5 秒内按下了提交按钮。

要进行故障排除，请执行以下步骤：

最简单的解决方案是调整用户体验，使得在输入长文本后的 0.5 秒内无法使用提交选项。例如，在提交查询之前添加一个确认对话框，或者简单地重新排序表单元素，使得在文本区域组件之后还有另一个字段需要完成。

其他解决方案是将文本区域组件替换为文本输入(Text Input)组件，该组件不包含防抖延迟。也可以使用Toast组件作为提交按钮按下和查询执行之间的延迟缓冲区，以确保经过足够的时间，使完整文本被包含在内。

返回顶部

函数(Functions)

我的函数不工作

Slate 中的函数是在沙箱中与应用程序其余部分隔离执行的基本 JavaScript。它们纯粹是用户生成的代码，因此与函数相关的大多数问题归根结底都是对 JavaScript 的理解有误，或者未能正确实现所需功能。

要进行故障排除，请执行以下步骤：

调试的基本步骤是将函数简化，直到其行为符合预期，然后逐步添加复杂性，直到意外行为再次出现。此时，您已经确定了需要进一步研究以理解实现所需行为的正确方法的点。

另一个调试工具是 Chrome DevTools 调试器 ↗。也可以考虑相关章节使用 DevTool 进行调试。使用 debugger; 语句在函数中添加"断点"。

然后，在打开 Chrome DevTools 面板的情况下，单击函数窗口中的测试(Test)按钮。函数执行将在断点处暂停，您可以继续单步执行函数代码并查看变量的值。

返回顶部

我的函数未按预期运行

函数与事件框架的交互方式可能不直观，因为在正常使用中，它们不会被调用，而是由依赖图在其输入过时且其输出被渲染为 JSON 以供下游依赖使用时执行。

要进行故障排除，请执行以下步骤：

如果函数的行为出乎意料，请通过查看现有的最佳实践文档来确认您理解它们如何融入依赖图和事件框架。

很少需要事件调用 [f_myFunction].run 动作的模式。尝试依赖此模式的应用应重构为使用依赖图的正常解析。不要直接触发函数，而是更新上游依赖，例如通过触发查询或设置引用变量的值。

返回顶部

地图组件(Map widget)

我的 GEOJSON 未渲染

地图组件支持渲染正确定义的 geojson 地图要素，例如点和几何图形。这些可以动态生成或从数据库检索，但格式是特定的，如果是手动创建或通过新颖算法生成，可能难以实现。

要进行故障排除，请执行以下步骤：

查看地图组件中的 GeoJSON 参考示例。尝试在您的 Foundry 实例上搜索它，如果不可用，请提交问题。

返回顶部

样式(Styling)

我的样式未应用，或如何覆盖样式 [x]？

Slate 中的所有样式最终都转化为 CSS。您可以使用 Chrome 检查器工具（右键单击 > 检查(Inspect) 任何元素）检查应用的任何元素，以查看应用于该元素的类并理解文档层次结构。

要进行故障排除，请执行以下步骤：

查看关于样式的文档部分，以更深入地理解在 Slate 中如何以及在哪里定义、应用和渲染样式。

返回顶部

布局(Layout)

应用渲染问题

在某些配置中，如果您尝试将组件配置为"动态"宽度和高度，您可能会发现组件在页面加载时渲染在一个小框中。触发 [w_myWidget.resize] 动作会使组件渲染到预期大小。

此行为是由指定各种组件元素的宽度和高度为百分比（通常为 100%）的 CSS 与一个或多个父容器上的 Flex 属性之间的冲突引起的。由于这些冲突，Slate 无法在渲染时确定包含组件的元素的正确尺寸，因此将组件渲染得太小。

要进行故障排除，请执行以下步骤：

实现响应式组件尺寸的适当模式是仅在父容器和子组件上使用 Flex 配置设置。不要通过 CSS 手动设置其他 width 或 height 属性。要解决此问题，从根子组件开始，向上遍历所有父组件，移除任何位置或尺寸相关的 CSS 规则。

您可以使用 margin 和 padding 属性来嵌入或以其他方式对齐子组件。如果您熟悉 Flexbox CSS 规则，可以使用 Chrome 检查器来识别要定位的元素和类，并提供覆盖或额外的 Flexbox 规则以实现精确的期望行为。

返回顶部

我的 Slate 应用无法打印，或如何导出我的应用

Slate 针对快速应用开发进行了优化。底层框架对布局或样式的可配置性施加的限制很少。因此，Slate 无法以适合打印媒体或导出的方式通用地渲染所有应用。应用开发者需要针对每个应用投入时间来支持打印功能。

要进行故障排除，请执行以下步骤：

首先也是最好的选择是考虑为什么需要或要求打印您的应用。您的用户是否只是需要一种方法来保存他们创建的视图，以便以后参考或在演示中使用？

在这种情况下，考虑使用内置的可共享视图功能，该功能生成一个唯一的 URL，保存所有组件选择和变量的状态。用户可以在查看模式下从操作(Actions)下拉菜单访问此功能。

如果您确实需要打印或导出，那么您需要定义额外的媒体 CSS 样式来帮助您的应用正确渲染。

首先，您至少需要在全局样式(Global Styles)中添加以下内容：

@media print {
  @page {
    size: A4;
  }

  html, body , .ws-root-container.ws-sandbox {
    height: 600mm !important;
  }

  sl-app-view-actions {
    display: none !important;
  }
}

打印响应式应用或任何具有复杂样式或布局的应用将非常困难。在这些情况下，考虑创建一个"打印视图"作为单独的应用，通过 URL 参数接收必要的输入，并生成一个针对打印优化的简化视图。这将增加开发成本和维护负担，但会产生令人满意的行为。

返回顶部

性能(Performance)

我的应用加载缓慢或在编辑模式下卡顿

与所有 Web 应用一样，Slate 使用最终用户计算机上的浏览器资源来执行 JavaScript 代码，并使用 CSS 中指定的样式渲染 HTML 中定义的文档模型(DOM)。这些资源的一部分是恒定的；它们是在 Slate 框架内工作的开销。然而，在性能不佳的情况下，根本原因通常是一种应用过载形式，其中在应用开发过程中定义的配置要求浏览器提供过多资源来渲染应用、执行 JavaScript，或者仅仅是在内存中存储许多大型查询的结果。

在某些情况下，单个函数或查询可能是原因。在这种情况下，您可以使用应用依赖关系(Dependencies)选项卡中的性能指标来查看各种查询和函数的节点时间(Time in Node)。此指标表示在页面加载时解析该特定节点所花费的持续时间，这有助于识别应用瓶颈的可能候选者。

通常，最佳实践是倾向于轻量级、边界清晰、单一用途的应用，并通过它们之间的深度链接，从"集群"的小型应用创建大型工作流或应用。

返回顶部

配置(Configuration)

文档过大无法保存

Slate 将应用配置保存为 JSON 文档，其大小限制通常为 2,000,000 字节的 UTF-8 编码字符。尝试保存配置超过大小限制的 Slate 应用将失败，需要对应用配置进行更改以减小大小。已打开的 Slate 应用的 JSON 文档可以通过导出获取。

Slate 应用的每个部分都会在一定程度上占用配置大小，编辑器应注意正在构建的 Slate 应用的规模以及嵌入在应用配置中的资源。以下是过度使用配置大小的常见原因以及建议的解决方案：

Base64 编码的图像

将图像上传到 Foundry，并使用图像组件引用该图像。

大型函数

考虑重构函数，将通用逻辑提取到函数库中。

此外，大型函数可能更适合作为通过平台编辑器使用的 Foundry 函数。

大型函数库

虽然函数库在 Slate 应用的所有页面之间共享以节省空间，但 JavaScript 库可能非常大。要么重构自定义库以使用共享逻辑，要么使用外部库的压缩版本。

返回顶部